feat(platform): add sentry platform list command - #1366

…ons, dataset list (#1400)

## Documentation Audit Report (2026-08-10)

Weekly automated audit of the Sentry CLI repository comparing
documentation against implementation.

---

## Changes in This PR

### 1. AGENTS.md — Zod → Valibot migration drift (HIGH IMPACT)

PR #1389 (merged 2026-08-07) removed all remaining Zod usage and
migrated to Valibot. However, AGENTS.md was not updated, leaving AI
agents with incorrect guidance that would produce non-compiling code.

**Fixed:**
- Renamed "Zod Schemas for Validation" → "Valibot Schemas for
Validation"
- Rewrote code examples to use the Valibot API (`object`, `string`,
`optional`, `InferOutput`, `safeParse`)
- Fixed import example from `import { z } from "zod"` → `import {
object, string, optional } from "valibot"`
- Fixed stale import path `../../lib/config.js` → `../../lib/db/auth.js`
for `getAuthToken`
- Updated architecture description ("TypeScript types and Zod schemas" →
"Valibot schemas")
- Updated "No Runtime Dependencies" rule ("redundant Zod schemas" →
"redundant Valibot schemas")

### 2. Version pin examples — 0.40.0 → 0.42.2

The latest release is 0.42.2 (three minor versions ahead of the
documented pin).

**Fixed in:**
- `apps/cli-docs/src/content/docs/getting-started.mdx` —
`SENTRY_VERSION=0.40.0` → `0.42.2`
- `packages/cli/install` — help text and examples updated from `0.40.0`
→ `0.42.2`

### 3. agent-guidance.md — Stale dashboard dataset list

The documented dataset list used internal API names (`tracemetrics`,
`error-events`) instead of user-facing aliases. Also missing
`transactions` alias.

**Fixed:** Updated to show user-facing names: `spans` (default),
`errors`, `transactions`, `metrics`, `issue`, `logs`.

---

## Full Gap Report

### A. Undocumented or missing commands/subcommands

**No gaps.** All commands in `src/commands/` have corresponding doc
fragments in `apps/cli-docs/src/fragments/commands/`. Command docs are
auto-generated from code metadata + fragments, so coverage is inherently
complete. The new `platform` command (#1366) already has its fragment.

### B. Undocumented flags

**No gaps.** Non-hidden flags are auto-generated into Options tables by
the doc generator (`script/generate-command-docs.ts`). This was verified
by checking the generated output for recent additions.

### C. Missing usage examples

All command groups have bash examples in their fragments. Lower-priority
gaps:
- `sentry help --json` (new in #1337) has no dedicated example in the
help fragment (only available via `--help`)
- `sentry cli fix` fragment exists but is minimal

### D. Stale descriptions

**No gaps found.** The `brief` strings in code match the generated doc
descriptions.

### E. Missing route mappings in skill generator

**Not applicable.** `ROUTE_TO_REFERENCE` was removed in favor of
automatic 1:1 mapping via `groupRoutesByReference()`. All routes are
automatically covered.

### F. Installation / distribution gaps

| Gap | Source | Doc |
|-----|--------|-----|
| Install script `--no-modify-path` / `--no-completions` flags |
`packages/cli/install` | Not in `getting-started.mdx` (available via
`--help`) |
| Two install URLs coexist: `cli.sentry.dev/install` vs
`sentry.io/get-cli/` | redirect config | Not documented (redirect is
transparent) |
| **Version pin examples stale (0.40.0)** | install script,
getting-started.mdx | **Fixed in this PR** |

### G. Undocumented environment variables

**No gaps.** `configuration.md` is generated from
`src/lib/env-registry.ts`, which is the single source of truth.
Internal-only variables (`SENTRY_PIPELINE`, `SENTRY_MONITOR_SLUG`, etc.)
are intentionally excluded.

### H. Auth / self-hosted gaps

**No new gaps.** Self-hosted docs (26.1.0+ OAuth requirement,
`SENTRY_CLIENT_ID`, trust anchors) are accurate. The new `sentry auth`
smart default (login when logged out, status when logged in, PR #1380)
is already documented in the auth fragment.

### I. Plugin/skills gaps

Low-priority items (unchanged from prior audit):
- `agent-skills.ts` only installs to `.claude` and `.agents` directories
— other detected agents (Windsurf, Copilot, etc.) are detected for
telemetry only, not skill installation
- This is technically accurate in `agentic-usage.md` ("Skills are also
refreshed... skill files are embedded in the binary") but could be
clearer about which agents get auto-installed skills vs. which are only
detected

### J. README / DEVELOPMENT.md drift

| Gap | Source | Doc |
|-----|--------|-----|
| **AGENTS.md references Zod throughout** | `src/types/` uses Valibot
after #1389 | **Fixed in this PR** |
| AGENTS.md import example uses stale path `lib/config.js` |
`getAuthToken` is in `lib/db/auth.js` | **Fixed in this PR** |

---

## Top 5 Most Impactful Fixes (Prioritized)

1. **✅ AGENTS.md Zod → Valibot** — AI agents will write non-compiling
code using `import { z } from "zod"` because AGENTS.md instructs them
to. This causes immediate build failures for any AI-assisted
contribution.

2. **✅ Version pin examples** — Users following the install docs will
pin to a version 3 releases behind, potentially missing security fixes
and new features.

3. **✅ Dashboard dataset aliases** — Agents using the documented
`tracemetrics` or `error-events` names work, but the user-facing aliases
(`metrics`, `errors`) are more discoverable and match `--help` output.

4. **Low priority: `--no-modify-path` / `--no-completions` installer
flags** — Power users in CI/Docker may want these, but they're available
via `--help` on the script itself.

5. **Low priority: Skill install target clarification** — Only `.claude`
and `.agents` get auto-installed skills; other agents are detected for
telemetry only. This is technically correct in the docs but could be
made more explicit.

<div><a
href="https://cursor.com/agents/bc-e1379371-9ad9-4d53-8665-bb60c5e961e0?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>